API Reference (Planning Space version: 20.3 Update 12 (20.3.12))
Important: For correct API reference information, you should ensure that the version of this document matches with the version of your Planning Space server. See the version number in the heading and 'Software version' in every page footer.
The topics in this section contain API reference information for five APIs which provide access to application functionality:
- Dataflow Web API (V1 and V2)
- Economics Web API
- Economics Calculation Web API
- Financials Web API
- PlanningSpace Web API
Integration Services (OData) API requests provide access only to the '/data' resources of these APIs.
Authorization
Authorization to use API resources is determined by the user account that has been used to authenticate the Web API session, or Integration Services API request. When a user account does not have authorization to use an API resource, the API server will send a '403 Forbidden' response. The user account must be a member of a tenant workgroup that is assigned access to the tenant role which governs the API resource; for example the 'Security' role governs access to all user management functions, and this is normally only granted to members of the 'Administrators' workgroup. Administrators can perform user management via the PlanningSpace API, and modify user accounts and workgroups.
Integration Services API requests are only authorized for '/data' API resources, even where the user account has additional degrees of access.
For general information about workgroups and roles, see the Planning Space Deployment Guide.
HTTP methods used by the Web API
The Web API implements the following HTTP methods for its operations, based on the conventions for RESTful API design:
| Method | Description |
|---|---|
| GET | Retrieves a resource. |
| POST | Creates a new resource or performs an action on the specified resource. |
| PUT | Replaces or updates an existing resource. Used in the Dataflow V2 API. |
| PATCH | Performs a partial update on an existing resource (that is, only changes are sent in the API request). |
| DELETE | Deletes a resource. |
PATCH requests
PATCH requests use the JSON Patch format (see http://jsonpatch.com). However, do not use "application/json-patch+json" as Content-Type, just use "application/json".
The Using PATCH requests page contains some detailed examples of PATCH requests for the PlanningSpace API.
Note that the live Swagger-based API reference may show incorrect model information for PATCH requests - please use the information below and in Using PATCH requests.
'Single item' PATCH requests
There are PATCH requests in the PlanningSpace API which make changes to a single user account, role definition, or workgroup definition.
In these cases, the body of the PATCH request must be an array of patch operations, such as:
PATCH /PlanningSpace/api/v1/users/157
Content-Type: "application/json"
[ {"value": true, "path":"/isAccountLocked", "op": "replace"} ]
or
PATCH /PlanningSpace/api/v1/users/156
Content-Type: "application/json"
[ {"value": true, "path":"/isDeactivated", "op": "replace"}, {"value":"DEACTIVATED user account", "path": "/description", "op": "replace"} ]
The response to a successful patch will be an object with key "entity" and value equal to the settings of the modified (in this case) user account (output is abbreviated):
{"entity":{"id":157,"displayName":"IPS_Admin_User2", ... }}
Notes for using PATCH requests:
- the PATCH operations may be applied in any order;
- if any operation fails then the whole PATCH request will be aborted;
- the JSON Patch 'test' operation is not currently implemented by the Web API.
Bulk PATCH requests
The 'bulk' PATCH requests are used to change multiple user accounts, roles or workgroups.
In these cases, the body of the PATCH request must be a JSON object where each member key is an ID and each value is an array of patch operations. For example, the two PATCH examples above can be combined into one request using '/PlanningSpace/api/v1/users/bulk':
PATCH /PlanningSpace/api/v1/users/bulk
Content-Type: "application/json"
{"156": [{"value": true, "path":"/isDeactivated", "op": "replace"}, {"value":"DEACTIVATED user account", "path": "/description", "op": "replace"}],
"157": [{"value": true, "path":"/isAccountLocked", "op": "replace"}] }
Each member will be processed separately and the response will contain, for each key, the status code (200, or an error code), and the modified entity or an error response. For example (output is abbreviated):
{"156":{"statusCode":200,"response":{"entity": {...}},
"157":{"statusCode":200,"response":{"entity": {...}}}}
GET requests for users, workgroups and roles (and using the 'include' query)
In the PlanningSpace API, the '/api/v1/users', '/api/v1/roles' and '/api/v1/workgroups' API resources omit information by default. The contents of 'userWorkgroups', 'users', 'allowedRoles', etc. are not included in the response.
This can be modified by:
- using the 'include' query, for example
/api/v1/users?include=userWorkgroups,/api/v1/workgroups?include=users,allowedroles,deniedroles - using the '$select' query, for example
/api/v1/users?$select=userWorkgroups,/api/v1/users?$select=id,userworkgroups
How to use the API Reference
Click the API name in the left-hand menu (under 'API Reference') to display all of its API resource groups and operations. Alternatively, use the topic links below.